<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">

<head>

<title>Autocomplete - a jQuery plugin</title>

<style>
	html * {
		font-family: Arial, Helvetica, sans-serif;
	}

	h1 {
		font-size: 20pt;
	}

	h2 {
		font-size: 16pt;
	}

	h3 {
		font-size: 14pt;
	}

	h4 {
		font-size: 12pt;
	}

	p, div, blockquote {
		font-family: Verdana, Arial, Helvetica, sans-serif;
		font-size: 12pt;
	}
	
	p,
	dt,
	dd {
		padding-left: 20pt;
		max-width: 60em;
	}

	code {
		display: block;
		padding-left: 40pt;
		font-family: Consolas, Monaco, fixed;
	}
	
	dt {
		margin-top: 10pt;
	}
	
	dt code {
		display: inline;
		padding: 0;
	}

	dt b {
		padding-right: 40pt;
	}

	dd {
		padding-left: 25pt;
	}

	ul.revisions {
		list-style: none;
	}

	ul.revisions>li {
		padding: 10px 0;
	}
	ul.revisions>li ul {
		margin-top: 10px;
	}

	ul.revisions>li ul li {
		margin: 5px 0;
	}
</style>
</head>

<body>
	<h1>$Autocomplete - a jQuery plugin</h1>

	<p>
		This plugin for jQuery will allow you to associate an edit field with a pop-up list of matching items, which are
		updated as the user types.  Matching data can be obtained by Ajax queries or by matches against a static
		in-memory array of data elements.  Multiple options and events make this plugin adaptable to your needs.
	</p>
	<p>
		This is a modification of the jQuery Autocomplete Plug-in written by Dylan Verheul and then
		further modified by Pengoworks.  I made several improvements and fixes and I'm sharing them with
		the community.
	</p>
	<p>
		The project is hosted on <a href='http://code.google.com/p/jquery-ac/'>Google Code</a>.
	</p>

	<p>
		<strong>See also:</strong> <a href='screenshots.html'>Autocomplete Screen Shots</a>
	</p>

	<h4>Usage</h4>
	<code>
		$("selector").autocomplete(url [, options]);<br/>
		$("selector").autocompleteArray(array [, options]);
	</code>

	<h4>Demo page (search for City names in the state of Ohio (US))</h4>
	<code>http://www.pengoworks.com/workshop/jquery/autocomplete.htm</code>

	<h4>Advice</h4>
	<p>Make sure that selector selects only one element, unless you really, really know what you are doing.</p>
	
	<h2>Examples</h2>
	<p>
		(There is a <a href='autocomplete-screenshots.html'>separate page for screen shots</a> of the autocompleter in action.)
	</p>
	<h4>Example One</h4>
	<code>$("#input_box").autocomplete("autocomplete_ajax.cfm");</code>
	<p>
		In the above example, Autocomplete expects an input element with the id "input_box" to exist.
		When a user starts typing in the input box, the autocompleter will request autocomplete_ajax.cfm
		with a GET parameter named q that contains the current value of the input box. Let's assume that the
		user has typed "sp" (without quotes). Autocomplete will then request autocomplete_ajax.cfm?q=sp.
	</p>
		
	<p>You can see an example of the output here:</p>
	<code><a href='http://www.pengoworks.com/workshop/jquery/autocomplete_ajax.cfm?q=sp'>http://www.pengoworks.com/workshop/jquery/autocomplete_ajax.cfm?q=sp</a></code>
	<p>
		The backend should output possible values for the autocompleter, each on a single line.
		Output cannot contain the pipe symbol "|", since that is considered a separator (more on that later).
	</p>
	<p>
		An appropriate simple output would be:
	</p>
	<code>
		Sparta<br/>
		Spencer<br/>
		Spencerville<br/>
		Spring Valley<br/>
		Springboro<br/>
		Springfield
	</code>
	<p>NOTE: The autocompleter will present the options in the order the backend sends them.</p>

	<h4>Example Two</h4>
	<code>$("#input_box").autocompleteArray(["Allen","Albert","Alberto","Alladin"]);</code>
	<p>
		In the above example, and autocomplete box would be populated based on an array containing the items
		listed above. There are times when you have a very small subset of data you need to allow a user to
		select from and in those case AJAX operations are often overkill. You can load all the data locally
		and use an array to build your autocomplete suggestion list.
	</p>

	<h2>Options</h2>
	<p>
		You can pass advanced options as a JavaScript object, notation { name:value, ..., name: value }
	</p>
	<p>
	Example:
	</p>
	<code>$("#input_box").autocomplete("my_autocomplete_backend.php", { minChars:3 });</code>
	
	<p>These options are available:</p>
	
	<dl>
	<dt><b>autoFill</b> (default value: false)</dt>
		<dd>
			Whether or not the first match should be used to autofill in the input element.
			As you type, the first match will be filled in the input element as a best guess as to what
			you're looking for. Text you did not manually type will be pre-selected so typing the
			next character will make the guess go away and the next best match will be populated. 
		</dd>

	<dt><b>inputClass</b> (default value: "ac_input")</dt>
		<dd>
			This class will be added to the input box.
		</dd>
	
	<dt><b>resultsClass</b> (default value: "ac_results")</dt>
		<dd>
			The class for the UL that will contain the result items (result items are LI elements).
		</dd>

	<dt><a name='resultsIdOption'></a><b>resultsId</b> (default value: none)</dt>
		<dd>
			A DOM identifier for the UL that will contain the result items.  This ID is only added to the element
			when the element just before the element is shown, and is removed when the element is hidden.  This
			allows several autocompletes in the same DOM to share an ID for result items.
		</dd>

	<dt><b>loadingClass</b> (default value: "ac_loading")</dt>
		<dd>
			The class for the input box while results are being fetched from the server.
		</dd>
	
	<dt><b>lineSeparator</b> (default value: "\n")</dt>
		<dd>
			The character that separates lines in the results from the backend.
		</dd>
	
	<dt><b>cellSeparator</b> (default value: "|")</dt>
		<dd>
			The character that separates cells in the results from the backend.
		</dd>
	
	<dt><b>minChars</b> (default value: 1)</dt>
		<dd>
			The minimum number of characters a user has to type before the autocompleter activates.
		</dd>
	
	<dt><b>delay</b> (default value: 400)</dt>
		<dd>
			The delay in milliseconds the autocompleter waits after a keystroke to activate itself.
			If you're using the data property to set a local array, you may wish to increase the
			delay to a shorter time frame (such as 40ms.)
		</dd>
	
	<dt><b>cacheLength</b> (default value: 1)</dt>
		<dd>
			The number of backend query results to store in cache. If set to 1
			(the current result), no caching will happen. Do not set below 1.
		</dd>
	
	<dt><b>matchSubset</b> (default value: true)</dt>
		<dd>
			Whether or not the autocompleter can use a cache for more specific queries.
			This means that all matches of "foot" are a subset of all matches for "foo".
			Usually this is true, and using this options decreases server load and increases
			performance. Remember to set cacheLength to a bigger number, like 10.
		</dd>
	
	<dt><b>matchCase</b> (default value: false)</dt>
		<dd>
			Whether or not the comparison is case sensitive. Only important only if you use caching.
		</dd>
	
	<dt><b>matchContains</b> (default value: false)</dt>
		<dd>
			Whether or not the comparison looks inside (i.e. does "ba" match "foo bar")
			the search results. Only important if you use caching.
		</dd>
	
	<dt><b>maxItemsToShow</b>  (default value: -1)</dt>
		<dd>
			Limits the number of results that will be showed in the drop down. This is useful
			if you have a large dataset and don't want to provide the user with a list that could contain
			hundreds of items. To disable this feature, set the value to -1.
		</dd>
	
	<dt><b>mustMatch</b> (default value: false)</dt>
		<dd>
			If set to 1 (true), the autocompleter will only allow results that are presented by the backend.
			Note that illegal values result in an empty input box. In the example at the beginning of this
			documentation, typing "footer" would result in an empty input box.
		</dd>
	
	<dt><b>extraParams</b> (default value: {})</dt>
		<dd>
			Extra parameters for the backend. If you were to specify { bar:4 }, the autocompleter would call
			my_autocomplete_backend.php?q=foo&bar=4 (assuming the input box contains "foo").
		</dd>
	
	<dt><b>width</b> (default value: false)</dt>
		<dd>
			Sets the width of the drop down layer. If a non-positive integer is specified, then the width of
			the box will be determined by the width of the input element. Generally speaking, you'll want to
			leave this value alone. However, in some circumstances you may have a small input element where
			the drop down layer needs to display a lot of options. In that case, you can specify a larger size.
		</dd>
	
	<dt><b>selectFirst</b> (default value: false)</dt>
		<dd>
			If this is set to true, the first autocomplete value will be automatically selected on tab/return,
			even if it has not been handpicked by keyboard or mouse action. If there is a handpicked (highlighted)
			result, that result will take precedence.  If the user has not hand-picked an item, then the first item
			in the list will be hilighted.
		</dd>
	
	<dt><b>selectOnly</b> (default value: false)</dt>
		<dd>
			If this is set to true, and there is only one autocomplete when the user hits tab/return, it will
			be selected even if it has not been handpicked by keyboard or mouse action. This overrides selectFirst.
		</dd>
	
	<dt><b>formatItem</b> (default value: none)</dt>
		<dd>
			A JavaScript funcion that can provide advanced markup for an item. For each row of results, this
			function will be called. The returned value will be displayed inside an LI element in the results list.
			Autocompleter will provide 3 parameters: the results row, the position of the row in the list of results,
			and the number of items in the list of results. See the source code of
			<a href='http://www.dyve.net/jquery?autocomplete'>http://www.dyve.net/jquery?autocomplete</a> for an example.
		</dd>
	
	<dt><b>onItemSelect</b> (default value: none)</dt>
		<dd>
			A JavaScript function that will be called when an item is selected. The autocompleter will specify a single
			argument, being the LI element selected. This LI element will have an attribute "extra" that contains an
			array of all cells that the backend specified. See the source code of
			<a href='http://www.dyve.net/jquery?autocomplete'>http://www.dyve.net/jquery?autocomplete</a> for an example.
		</dd>
	
	<dt><b>onFindValue</b> (default value: none)</dt>
		<dd>
			A JavaScript function that will be called when the findValue() method is called.
			The function will be passed the select LI element &mdash; just like the onItemSelect function is.
		</dd>

	<dt><a name='onResultsShowOption'></a><b>onResultsShow</b> (default value: none)</dt>
		<dd>
			A JavaScript function that will be called just before the matching results popup is shown.
			The function will be passed the UL element representing the results.  If a
			<a href='#resultsIdOption'>resultsId</a> option was specified, then this function will
			be called after the ID has been set.
		</dd>

	<dt><a name='onResultsHideOption'></a><b>onResultsHide</b> (default value: none)</dt>
		<dd>
			A JavaScript function that will be called just after the matching results popup is hidden (closed).
			The function will be passed the UL element representing the results.  If a 
			<a href='#resultsIdOption'>resultsId</a> option was specified, then this function will
			be called before the ID has been removed from the UL element.
		</dd>

	<dt><a name='resultsParentOption'></a><b>resultsParent</b> (default value: input field)</dt>
		<dd>
			If specified, this allows you to override the parent for the autocomplete results window.
			The results popup will be aligned to the specified element just as though it were the edit field.
			The value may be a DOM element or a jQuery object.<br/><br/>
			This option is very useful when your edit field is wrapped into a more complex UI element.
		</dd>
	</dl>

	<h2>Advanced options</h2>
	<p>
		If you want to do more with your autocompleter, you can change some options on the fly.
		The autocompleter is accessed as an attribute of the input box.
	</p>
	<p>
		Example:
	</p>
	<code>
		// set the autocompleter<br/>
		var ac = $("#input_box").autocomplete("my_autocomplete_backend.php");<br/>
		// would look up the value of the autocomplete box based on the text in the input element<br/>
		ac[0].autocompleter.findValue(); 
	</code>
	<p>
		The following functions that can be called to influence the behaviour at run-time:
	</p>
	<dl>
		<dt><code>findValue()</code></dt>
			<dd>
				This will examine the value currently in the input element and look it's value up to see
				if it can find a matching value. This function can potentially perform an AJAX operation,
				therefore the findValue() function does not return a value. Instead, you need to specific a
				onFindValue callback function that will run. This method is valuable if you need to set the
				Autocomplete input element to a value via JavaScript and the "value" of the text field is
				mapped to extended properties stored in the LI element's "extra" property.
			</dd>

		<dt><code>flushCache()</code></dt>
			<dd>
				This flushes the cache.
			</dd>

		<dt><code>setExtraParams(obj)</code></dt>
			<dd>
				This sets the extra parameters of the autocompleter to obj (which should be a JavaScript object, see above).<br/>
				(It's often wise to flush the cache after calling setExtraParameters.)
			</dd>
	</dl>

	<h2>Download</h2>

	<p>
		You can download this code from the <a href='http://code.google.com/p/jquery-ac/downloads/list'>Google Code project</a>
	</p>

	<a name='changelog'></a>
	<h2>Revisions</h2>
	<ul class='revisions'>
		<li>
			<a href='http://dyve.net/jquery/?autocomplete'>Dylan Verheul</a>
			<ul>
				<li>Original code base.</li>
			</ul>
		</li>
		<li>
			<a href='http://www.pengoworks.com/workshop/jquery/autocomplete.htm'>Pengoworks</a>
			<ul>
				<li>Supports local data array (can now use w/out AJAX).</li>
				<li>Limit dropdown to XX number of results (good for limiting the results to users)</li>
				<li>Autofill pre-populates text box as you type</li>
				<li>New findValue() method can be used to programmatically determine if the value in the box is a valid option.
					(Useful for verifying the text entered is an existing value option.)</li>
				<li>Dropdown options now correctly re-position themselves on each display (which means they adjust for changing to the DOM)</li>
				<li>Dropdown box defaults to the width of the input field its attached to (you can manually specify a larger width as well)</li>
				<li>Better emulates Windows autocomplete boxes (for example: hitting delete and retyping the same box will now bring back the dropdown menu)</li>
				<li>Miscellaneous bug fixes</li>
			</ul>
		</li>
		<li>
			<strong>1.5</strong> &ndash; Ron Lussier (<a href='http://www.glassdoor.com/index.htm'>glassdoor.com</a>)
			<ul>
				<li>Added '<a href='#resultsIdOption'>resultsId</a>' option.</li>
				<li>Added '<a href='#resultsParentOption'>resultsParent</a>' option.</li>
				<li>Added '<a href='#onResultsShowOption'>onResultsShow</a>' &amp;
					'<a href='#onResultsHideOption'>onResultsHide</a>' options.</li>
				<li>Fixed problem with multiple ajax requests coming back in a different order.  Now while all requests will be cached, only the
					most recent will be displayed.</li>
				<li>Changed so that there is always a selection when using the 'selectFirst' option.  This will be the first item unless
					the user has explicitly selected something else.</li>
				<li>Added a version variable to the source code, currently set to 1.5</li>
			</ul>
		</li>
	</ul>
	<hr/>
	<p>
		Ron Lussier, <a href='http://www.glassdoor.com/index.htm'>Glassdoor.com</a> &ndash;
		<a href="&#109;&#097;&#105;&#108;&#116;&#111;&#058;%20%63%6fyo&#116;%65%40&#103;l%61s%73d%6f%6fr&#046;&#099;%6f&#109;">&#099;&#111;&#121;&#111;&#116;&#101;&#064;&#103;&#108;&#097;&#115;&#115;&#100;&#111;&#111;&#114;&#046;&#099;&#111;&#109;</a><br/>
		1 Oct 2009
	</p>
</body>
</html>
